package com.ics.atable.chat.service;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.IService;
import com.ics.atable.chat.model.entity.ChatSession;

import java.util.List;

/**
 * chat session service interface
 *
 * 提供对会话实体 {@link com.ics.atable.chat.model.entity.ChatSession} 的业务能力，
 * 在 MyBatis-Plus 通用接口基础上扩展更贴近业务的操作方法。
 *
 * 约定：
 * - 会话的主键为字符串 UUID。
 * - 逻辑删除通过将状态置为 "deleted" 实现。
 * - 归档通过将状态置为 "archived" 实现。
 * - 置顶通过字段 isPinned (0/1) 控制。
 *
 * @author haohongbin
 */
public interface ChatSessionService extends IService<ChatSession> {
	/**
	 * 创建会话。
	 * 若未传入 id，将在服务端生成 UUID；未传入的可选字段会按如下规则补全默认值：
	 * title=“新对话”，status="active"，isPinned=0。
	 *
	 * @param session 会话实体（id 可为空）
	 * @return 新建会话的 ID（UUID）
	 * @throws IllegalArgumentException 当 session 为空时
	 */
	String createSession(ChatSession session);

	/**
	 * 根据 ID 更新会话，仅更新非空字段。
	 *
	 * @param session 包含要更新字段且必须包含 id 的会话实体
	 * @return 更新是否成功
	 * @throws IllegalArgumentException 当 id 为空时
	 */
	boolean updateSession(ChatSession session);

	/**
	 * 将会话状态置为 "archived"。
	 *
	 * @param id 会话 ID
	 * @return 操作是否成功
	 * @throws IllegalArgumentException 当 id 为空时
	 */
	boolean archiveSession(String id);

	/**
	 * 逻辑删除：将会话状态置为 "deleted"。
	 *
	 * @param id 会话 ID
	 * @return 操作是否成功
	 * @throws IllegalArgumentException 当 id 为空时
	 */
	boolean deleteSession(String id);

	/**
	 * 设置/取消置顶状态。
	 *
	 * @param id 会话 ID
	 * @param pinned true 表示置顶；false 表示取消置顶
	 * @return 操作是否成功
	 * @throws IllegalArgumentException 当 id 为空时
	 */
	boolean pinSession(String id, boolean pinned);

	/**
	 * 查询某个用户的会话列表，过滤已删除状态，并按置顶与更新时间倒序排序。
	 *
	 * @param userId 用户 ID
	 * @return 会话列表
	 */
	List<ChatSession> listSessionsByUser(Long userId);

	/**
	 * 分页查询某个用户的会话，过滤已删除状态，并按置顶与更新时间倒序排序。
	 *
	 * @param userId 用户 ID
	 * @param page   当前页（从 1 开始）
	 * @param size   每页大小
	 * @return 分页结果
	 */
	Page<ChatSession> pageSessionsByUser(Long userId, long page, long size);
}
